For this workshop

Presenters: Maurits Evers, Sebastian Kurscheid
Slides: https://github.com/mevers/workshop_RMarkdown

What you should bring / have brought

1. A laptop with a recent RStudio release already installed
2. A set of questions
3. (Optional) A sample text document for you to layout in RMarkdown

What you should be familiar with

1. Basic R skills: Know what a dataframe is; how to produce a plot; how to inspect an element, …
2. Basic Unix/Linux skills

Important R packages

pkg <- c("ggplot2", "rmarkdown", "knitr", "dplyr");
lapply(pkg, function(x) { if (!require(x, character.only = TRUE, quietly = TRUE)) {
  install.packages(x);
  require(x, quietly = TRUE)}
})

Example data

We will use the starwars dataset from dplyr.

head(starwars, n = 3);

## # A tibble: 3 x 13
##             name height  mass hair_color  skin_color eye_color birth_year
##            <chr>  <int> <dbl>      <chr>       <chr>     <chr>      <dbl>
## 1 Luke Skywalker    172    77      blond        fair      blue         19
## 2          C-3PO    167    75       <NA>        gold    yellow        112
## 3          R2-D2     96    32       <NA> white, blue       red         33
## # ... with 6 more variables: gender <chr>, homeworld <chr>, species <chr>,
## #   films <list>, vehicles <list>, starships <list>

Create new RMarkdown (Rmd) document in RStudio

1. File \(\rightarrow\) New File \(\rightarrow\) R Markdown

2. Specify output option

   

3. Render

0. If you need help with setting up RStudio and the necessary packages, this is the time…

1. Create a new R Markdown (Rmd) document in RStudio.
2. Select PDF, HTML and Word as output option.
3. Render the RMarkdown document to the corresponding output formats.
4. Locate and open the final output file.
5. Change the output format of an existing RMarkdown document

Document conversion

1. Rmd \(\rightarrow\) PDF, HTML, Word uses rmarkdown::render() (note that knitr::pandoc() is deprecated)
2. rmarkdown::render() uses the universal document converter pandoc (installed as part of RStudio)

For example, pandoc will translate

# Header

into the following output-specific lines:

1. For HTML output

   <h1>Header</h1>

2. For \(\LaTeX\) output

   \section{Header}

Beware the different Markdown flavours: GitHub, R Markdown, vanilla Markdown, …

Here: Focus on RMarkdown, and the following elements

1. Headers
2. Emphasis: bold and italics
3. Lists: Ordered and unordered
4. Images and links
5. Blockquotes
6. Rules and line breaks

More details:

• Markdown basics
• R Markdown Cheat Sheet
• Markdown Cheat Sheet

1. Experiment with different markdown elements in your RMarkdown document
2. Render the document and check the resulting output file
3. Are there any specific text elements you would like to typeset?

You can use language-specific expressions in RMarkdown documents.

For example:

1. In HTML documents, you can use
   • <img src="path/to/image.png" style="width:200px;"> to place an image,
   • <hr> to place a horizontal rule,
   • <ol start="10"><li>...</ol> to create an ordered list,
   • most HTML code tags.
2. In PDF documents, you can use
   • \includegraphics[width=\textwidth]{...} to place an image,
   • \begin{minipage}{.5\textwidth}...\end{minipage} to fine-tune horizontal and vertical text/figure layout,
   • a lot of the \(\LaTeX\) syntax.

Beware: A HTML statement won't be recognised if you render your RMarkdown file as a Word document.

---
title: "Main title"
subtitle: "Subtitle"
author: "Firstname Lastname"
date: "07/08/2017"
output:
  word_document
---

Main keys

1. Title and subtitle
2. Author (can have multiple authors as list for key author)
3. Date (can be R code, e.g. format(Sys.time(), '%d %B %Y'))
4. Output option: html_document, pdf_document, word_document, ioslides_presentation, beamer_presentation

1. Make changes to the existing YAML header keys (title, author and date)
2. Add a subtitle to your document
3. Add multiple authors
4. Change the output from a Word document to a ioslides presentation

Some useful options

• eval=FALSE: Don't run code.
• include=FALSE: Run code but don't include the chunk in the output document.
• echo=FALSE: Don't show code, show results.
• results='hide': Show code, don't show results.
• message=FALSE: Don't show any additional R messages.
• error=FALSE: Don't show R error messages.
• warning=FALSE: Don't show R warning messages.
• cache=TRUE: Use cached results (if available) until the code chunk is changed.
• fig.width=7, fig.height=7: Set actual figure width and height to 7 inches.
• out.width=5, out.height=5: Set output document figure width and height to 5 inches; if fig.width, fig.height are different, the output is scaled.

More chunk options can be found e.g. in the R Markdown Reference Guide and in knitr's documentation.

1. Write R code to show a barplot of how many characters participated in every Star Wars film.
2. Include a code chunk without executing it.
3. Disable R output from an R code chunk.
4. Only show the output of an R code chunk.
5. Change the dimension of a (gg)plot.

Hint:

# R code
df <- cbind.data.frame(film = unlist(starwars$films));
ggplot(data = df, aes(film)) + geom_bar();

1. General: How to output tables/dataframes?
2. knitr::kable()
3. tibble::print.tbl_df()
4. DT::datatable()

suppressMessages(library(knitr));
kable(starwars[1:4, 1:4])

suppressMessages(library(DT));
#DT::datatable(starwars, options = list(dom = "ftp", scrollX = TRUE, pageLength = 4));
DT::datatable(starwars[, 1:4], options = list(pageLength = 8));

1. plotly
2. D3 in R

Load the necessary libraries

suppressMessages(library(ggplot2));
suppressMessages(library(plotly));

## Warning: package 'plotly' was built under R version 3.4.1

suppressMessages(library(scatterD3));

ggplotly(ggplot(starwars, aes(x = height, y = mass, label = name)) + geom_point(), height = 5);

scatterD3(x = starwars$height, y = starwars$mass, lab = starwars$name);

R Markdown and shiny

…